---
id: create-run
title: "Create a run"
description: "Creates a new run object for a job."
sidebar_label: "Create a run"
hide_title: true
hide_table_of_contents: true
api:
  {
    "operationId": "createRun",
    "description": "Creates a new run object for a job.",
    "deprecated": true,
    "tags": ["Jobs"],
    "requestBody":
      {
        "content":
          {
            "application/json":
              {
                "schema":
                  {
                    "type": "object",
                    "properties":
                      {
                        "id":
                          {
                            "description": "An _optional_ user-provided unique ID of the run. A run ID **must** be an [UUID](https://tools.ietf.org/html/rfc4122). If an ID for the run is not provided, a random UUID will be generated for the given run.",
                            "type": "string",
                            "format": "uuid",
                          },
                        "nominalStartTime":
                          {
                            "description": "An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal start time of the run.",
                            "type": "string",
                            "format": "date-time",
                          },
                        "nominalEndTime":
                          {
                            "description": "An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal end time of the run.",
                            "type": "string",
                            "format": "date-time",
                          },
                        "args":
                          {
                            "description": "The arguments of the run.",
                            "type": "object",
                          },
                      },
                    "example":
                      {
                        "args":
                          {
                            "email": "me@example.com",
                            "emailOnFailure": false,
                            "emailOnRetry": true,
                            "retries": 1,
                          },
                      },
                    "title": "CreatedRun",
                  },
              },
          },
      },
    "responses":
      {
        "201":
          {
            "description": "CREATED",
            "content":
              {
                "application/json":
                  {
                    "schema":
                      {
                        "type": "object",
                        "anyOf":
                          [
                            {
                              "type": "object",
                              "example":
                                {
                                  "id": "870492da-ecfb-4be0-91b9-9a89ddd3db90",
                                  "createdAt": "2019-05-09T19:49:24.201361Z",
                                  "updatedAt": "2019-05-09T19:49:24.201361Z",
                                  "nominalStartTime": null,
                                  "nominalEndTime": null,
                                  "state": "RUNNING",
                                  "startedAt": "2019-05-09T15:17:32.690346",
                                  "endedAt": null,
                                  "durationMs": null,
                                  "args":
                                    {
                                      "email": "me@example.com",
                                      "emailOnFailure": "false",
                                      "emailOnRetry": "true",
                                      "retries": "1",
                                    },
                                  "facets": {},
                                },
                              "title": "IncompleteRun",
                            },
                            { "type": "object" },
                          ],
                        "example":
                          {
                            "id": "870492da-ecfb-4be0-91b9-9a89ddd3db90",
                            "createdAt": "2019-05-09T19:49:24.201361Z",
                            "updatedAt": "2019-05-09T19:49:24.201361Z",
                            "nominalStartTime": null,
                            "nominalEndTime": null,
                            "state": "COMPLETED",
                            "startedAt": "2019-05-09T15:17:32.690346",
                            "endedAt": "2019-05-09T20:05:46.815920Z",
                            "durationMs": 4250894125,
                            "args":
                              {
                                "email": "me@example.com",
                                "emailOnFailure": "false",
                                "emailOnRetry": "true",
                                "retries": "1",
                              },
                            "context": { "SQL": "SELECT * FROM mytable;" },
                            "facets": {},
                          },
                        "title": "Run",
                      },
                  },
              },
          },
      },
    "parameters":
      [
        {
          "name": "namespace",
          "in": "path",
          "description": "The name of the namespace.",
          "required": true,
          "schema":
            { "type": "string", "maxLength": 1024, "example": "my-namespace" },
        },
        {
          "name": "job",
          "in": "path",
          "description": "The name of the job.",
          "required": true,
          "schema":
            { "type": "string", "maxLength": 1024, "example": "my-job" },
        },
      ],
    "method": "post",
    "path": "/namespaces/{namespace}/jobs/{job}/runs",
    "servers":
      [
        {
          "url": "http://localhost:5000/api/v1",
          "description": "Local API server",
        },
      ],
    "jsonRequestBodyExample":
      {
        "args":
          {
            "email": "me@example.com",
            "emailOnFailure": false,
            "emailOnRetry": true,
            "retries": 1,
          },
      },
    "info":
      {
        "title": "Marquez",
        "version": "0.50.0",
        "description": "Marquez is an open source **metadata service** for the **collection**, **aggregation**, and **visualization** of a data ecosystem's metadata.",
        "license":
          {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html",
          },
      },
    "postman":
      {
        "name": "Create a run",
        "description":
          {
            "content": "Creates a new run object for a job.",
            "type": "text/plain",
          },
        "url":
          {
            "path": ["namespaces", ":namespace", "jobs", ":job", "runs"],
            "host": ["{{baseUrl}}"],
            "query": [],
            "variable":
              [
                {
                  "disabled": false,
                  "description":
                    {
                      "content": "(Required) The name of the namespace.",
                      "type": "text/plain",
                    },
                  "type": "any",
                  "value": "",
                  "key": "namespace",
                },
                {
                  "disabled": false,
                  "description":
                    {
                      "content": "(Required) The name of the job.",
                      "type": "text/plain",
                    },
                  "type": "any",
                  "value": "",
                  "key": "job",
                },
              ],
          },
        "header":
          [
            { "key": "Content-Type", "value": "application/json" },
            { "key": "Accept", "value": "application/json" },
          ],
        "method": "POST",
        "body":
          {
            "mode": "raw",
            "raw": '""',
            "options": { "raw": { "language": "json" } },
          },
      },
  }
sidebar_class_name: "post api-method"
info_path: docs/api/marquez
custom_edit_url: null
---

import ApiTabs from "@theme/ApiTabs";
import MimeTabs from "@theme/MimeTabs";
import ParamsItem from "@theme/ParamsItem";
import ResponseSamples from "@theme/ResponseSamples";
import SchemaItem from "@theme/SchemaItem";
import SchemaTabs from "@theme/SchemaTabs";
import DiscriminatorTabs from "@theme/DiscriminatorTabs";
import TabItem from "@theme/TabItem";

## Create a run

:::caution deprecated

This endpoint has been deprecated and may be removed in future versions of the API.

:::

Creates a new run object for a job.

<details style={{"marginBottom":"1rem"}} data-collapsed={false} open={true}><summary style={{}}><strong>Path Parameters</strong></summary><div><ul><ParamsItem className={"paramsItem"} param={{"name":"namespace","in":"path","description":"The name of the namespace.","required":true,"schema":{"type":"string","maxLength":1024,"example":"my-namespace"}}}></ParamsItem><ParamsItem className={"paramsItem"} param={{"name":"job","in":"path","description":"The name of the job.","required":true,"schema":{"type":"string","maxLength":1024,"example":"my-job"}}}></ParamsItem></ul></div></details><MimeTabs><TabItem label={"application/json"} value={"application/json-schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Request Body</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"id"} required={false} schemaName={"uuid"} qualifierMessage={undefined} schema={{"description":"An _optional_ user-provided unique ID of the run. A run ID **must** be an [UUID](https://tools.ietf.org/html/rfc4122). If an ID for the run is not provided, a random UUID will be generated for the given run.","type":"string","format":"uuid"}}></SchemaItem><SchemaItem collapsible={false} name={"nominalStartTime"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal start time of the run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"nominalEndTime"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal end time of the run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"args"} required={false} schemaName={"object"} qualifierMessage={undefined} schema={{"description":"The arguments of the run.","type":"object"}}></SchemaItem></ul></details></TabItem></MimeTabs><div><ApiTabs><TabItem label={"201"} value={"201"}><div>

CREATED

</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><div><span className={"badge badge--info"}>anyOf</span><SchemaTabs><TabItem label={"IncompleteRun"} value={"0-item-properties"}><SchemaItem collapsible={false} name={"id"} required={false} schemaName={"uuid"} qualifierMessage={undefined} schema={{"description":"The ID of the run.","type":"string","format":"uuid"}}></SchemaItem><SchemaItem collapsible={false} name={"createdAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the run was created.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"updatedAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the run was updated.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"nominalStartTime"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal start time of the run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"nominalEndTime"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal end time of the run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"state"} required={false} schemaName={"string"} qualifierMessage={"**Possible values:** [`NEW`, `RUNNING`, `COMPLETED`, `FAILED`, `ABORTED`]"} schema={{"description":"The current state of the run.","type":"string","enum":["NEW","RUNNING","COMPLETED","FAILED","ABORTED"]}}></SchemaItem><SchemaItem collapsible={false} name={"startedAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the start time of the run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"endedAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the end time of the run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"durationMs"} required={false} schemaName={"integer"} qualifierMessage={undefined} schema={{"type":"integer","description":"The total duration of the run. Measured in milliseconds."}}></SchemaItem><SchemaItem collapsible={false} name={"args"} required={false} schemaName={"object"} qualifierMessage={undefined} schema={{"description":"The arguments of the run.","type":"object"}}></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>facets</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

The facets of the run. For a full list of standard run facets, see [OpenLineage](https://github.com/OpenLineage/OpenLineage/blob/main/spec/OpenLineage.md#standard-facets).

</div><SchemaItem collapsible={false} name={"description"} required={false} schemaName={""} qualifierMessage={undefined} schema={"A custom facet enables the extension of _dataset_, _job_, and _run_ metadata. A custom facet **must** also have a schema, where a version of the schema is identifiable via a URL. A field within the schema **must** not start with an underscore (`_`)."}></SchemaItem><SchemaItem collapsible={false} name={"allOf"} required={false} schemaName={""} qualifierMessage={undefined} schema={[{"description":"All base facet fields are prefixed with an underscore (`_`) to avoid field naming conflicts defined with other facets.","type":"object","properties":{"_producer":{"description":"URI identifying the producer of this metadata. For example this could be a git url with a given tag or sha","type":"string","format":"uri","example":"https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client"},"_schemaURL":{"description":"The URL to the corresponding version of the schema definition following a $ref URL Reference (see https://swagger.io/docs/specification/using-ref/)","type":"string","format":"uri","example":"https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/spec/OpenLineage.yml#MyCustomJobFacet"}},"required":["_producer","_schemaURL"],"title":"BaseFacet"},{"type":"object","additionalProperties":true}]}></SchemaItem><SchemaItem collapsible={false} name={"title"} required={false} schemaName={""} qualifierMessage={undefined} schema={"CustomFacet"}></SchemaItem></div></details></SchemaItem></TabItem><TabItem label={"MOD2"} value={"1-item-properties"}><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>jobVersion</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"namespace"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The namespace of the job."}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The name of the job."}}></SchemaItem><SchemaItem collapsible={false} name={"version"} required={false} schemaName={"uuid"} qualifierMessage={undefined} schema={{"type":"string","format":"uuid","description":"The version of the job."}}></SchemaItem></div></details></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>inputDatasetVersions</strong><span style={{"opacity":"0.6"}}> object[]</span></summary><div style={{"marginLeft":"1rem"}}><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem","paddingBottom":".5rem"}}>Array [</div></li><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>datasetVersionId</strong><span style={{"opacity":"0.6"}}> object</span><strong style={{"fontSize":"var(--ifm-code-font-size)","color":"var(--openapi-required)"}}> required</strong></summary><div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"namespace"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The namespace of the dataset."}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The name of the dataset."}}></SchemaItem><SchemaItem collapsible={false} name={"version"} required={true} schemaName={"uuid"} qualifierMessage={undefined} schema={{"type":"string","format":"uuid","description":"The version of the dataset."}}></SchemaItem></div></details></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>facets</strong><span style={{"opacity":"0.6"}}> object</span><strong style={{"fontSize":"var(--ifm-code-font-size)","color":"var(--openapi-required)"}}> required</strong></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

Dataset facets in run context, like `inputFacets`.

</div><SchemaItem name={"property name*"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}} collapsible={false} discriminator={false}></SchemaItem></div></details></SchemaItem><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem"}}>]</div></li></div></details></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>outputDatasetVersions</strong><span style={{"opacity":"0.6"}}> object[]</span></summary><div style={{"marginLeft":"1rem"}}><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem","paddingBottom":".5rem"}}>Array [</div></li><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>datasetVersionId</strong><span style={{"opacity":"0.6"}}> object</span><strong style={{"fontSize":"var(--ifm-code-font-size)","color":"var(--openapi-required)"}}> required</strong></summary><div style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"namespace"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The namespace of the dataset."}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The name of the dataset."}}></SchemaItem><SchemaItem collapsible={false} name={"version"} required={true} schemaName={"uuid"} qualifierMessage={undefined} schema={{"type":"string","format":"uuid","description":"The version of the dataset."}}></SchemaItem></div></details></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>facets</strong><span style={{"opacity":"0.6"}}> object</span><strong style={{"fontSize":"var(--ifm-code-font-size)","color":"var(--openapi-required)"}}> required</strong></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

Dataset facets in run context, like `outputFacets`.

</div><SchemaItem name={"property name*"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string"}} collapsible={false} discriminator={false}></SchemaItem></div></details></SchemaItem><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem"}}>]</div></li></div></details></SchemaItem><SchemaItem collapsible={false} name={"context"} required={false} schemaName={"object"} qualifierMessage={undefined} schema={{"description":"A key/value pair that must be of type `string`. A context can be used for getting additional details about the job.","type":"object","deprecated":true}}></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>facets</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

The facets of the run. For a full list of standard run facets, see [OpenLineage](https://github.com/OpenLineage/OpenLineage/blob/main/spec/OpenLineage.md#standard-facets).

</div><SchemaItem collapsible={false} name={"description"} required={false} schemaName={""} qualifierMessage={undefined} schema={"A custom facet enables the extension of _dataset_, _job_, and _run_ metadata. A custom facet **must** also have a schema, where a version of the schema is identifiable via a URL. A field within the schema **must** not start with an underscore (`_`)."}></SchemaItem><SchemaItem collapsible={false} name={"allOf"} required={false} schemaName={""} qualifierMessage={undefined} schema={[{"description":"All base facet fields are prefixed with an underscore (`_`) to avoid field naming conflicts defined with other facets.","type":"object","properties":{"_producer":{"description":"URI identifying the producer of this metadata. For example this could be a git url with a given tag or sha","type":"string","format":"uri","example":"https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client"},"_schemaURL":{"description":"The URL to the corresponding version of the schema definition following a $ref URL Reference (see https://swagger.io/docs/specification/using-ref/)","type":"string","format":"uri","example":"https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/spec/OpenLineage.yml#MyCustomJobFacet"}},"required":["_producer","_schemaURL"],"title":"BaseFacet"},{"type":"object","additionalProperties":true}]}></SchemaItem><SchemaItem collapsible={false} name={"title"} required={false} schemaName={""} qualifierMessage={undefined} schema={"CustomFacet"}></SchemaItem></div></details></SchemaItem></TabItem></SchemaTabs></div></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"id\": \"870492da-ecfb-4be0-91b9-9a89ddd3db90\",\n  \"createdAt\": \"2019-05-09T19:49:24.201361Z\",\n  \"updatedAt\": \"2019-05-09T19:49:24.201361Z\",\n  \"nominalStartTime\": null,\n  \"nominalEndTime\": null,\n  \"state\": \"COMPLETED\",\n  \"startedAt\": \"2019-05-09T15:17:32.690346\",\n  \"endedAt\": \"2019-05-09T20:05:46.815920Z\",\n  \"durationMs\": 4250894125,\n  \"args\": {\n    \"email\": \"me@example.com\",\n    \"emailOnFailure\": \"false\",\n    \"emailOnRetry\": \"true\",\n    \"retries\": \"1\"\n  },\n  \"context\": {\n    \"SQL\": \"SELECT * FROM mytable;\"\n  },\n  \"facets\": {}\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>

